﻿// -----------------------------------------------------------------------
// <copyright file="IStreamWriter.cs" company="Company">
// Company 2011
// </copyright>
// -----------------------------------------------------------------------

using System;
using System.Runtime.InteropServices;
using System.Security;
using System.Text;

namespace Company.IO.Interfaces
{
    /// <summary>
    /// Implements a TextWriter for writing characters to a stream in a particular encoding.
    /// </summary>
    [Guid("8404e736-73ae-4f12-819f-b181af63d6fb")]
    public interface IStreamWriter
    {
        /// <summary>
        /// Gets or sets a value indicating whether the StreamWriter will flush its buffer to the underlying stream after every call to StreamWriter.Write.
        /// </summary>
        bool AutoFlush { get; set; }

        /// <summary>
        /// Gets the underlying stream that interfaces with a backing store.
        /// </summary>
        IStream BaseStream { get; }

        /// <summary>
        /// Gets the Encoding in which the output is written.
        /// </summary>
        Encoding Encoding { get; }

        /// <summary>
        /// Closes the current StreamWriter object and the underlying stream.
        /// </summary>
        /// <exception cref="EncoderFallbackException">
        /// The current encoding does not support displaying half of a Unicode surrogate pair.
        /// </exception>
        void Close();

        /// <summary>
        /// Clears all buffers for the current writer and causes any buffered data to be written to the underlying stream.
        /// </summary>
        /// <exception cref="ObjectDisposedException">
        /// The current writer is closed.
        /// </exception>
        /// <exception cref="IIOException">
        /// An I/O error has occurred.
        /// </exception>
        /// <exception cref="EncoderFallbackException">
        /// The current encoding does not support displaying half of a Unicode surrogate pair.
        /// </exception>
        void Flush();

        /// <summary>
        /// Writes a character to the stream.
        /// </summary>
        /// <param name="value">The character to write to the text stream.</param>
        /// <exception cref="ObjectDisposedException">
        /// AutoFlush is true or the StreamWriter buffer is full, and current writer is closed.
        /// </exception>
        /// <exception cref="IIOException">
        /// An I/O error has occurred.
        /// </exception>
        /// <exception cref="NotSupportedException">
        /// AutoFlush is true or the StreamWriter buffer is full, 
        /// and the contents of the buffer cannot be written to the 
        /// underlying fixed size stream because the StreamWriter is at the end the stream.
        /// </exception>
        void Write(char value);

        /// <summary>
        /// Writes a character array to the stream.
        /// </summary>
        /// <param name="buffer">A character array containing the data to write. If buffer is a null reference (Nothing in Visual Basic), nothing is written.</param>
        /// <exception cref="ObjectDisposedException">
        /// AutoFlush is true or the StreamWriter buffer is full, and current writer is closed.
        /// </exception>
        /// <exception cref="IIOException">
        /// An I/O error has occurred.
        /// </exception>
        /// <exception cref="NotSupportedException">
        /// AutoFlush is true or the StreamWriter buffer is full, 
        /// and the contents of the buffer cannot be written to the 
        /// underlying fixed size stream because the StreamWriter is at the end the stream.
        /// </exception>
        [SecuritySafeCritical]
        void Write(char[] buffer);

        /// <summary>
        /// Writes a subarray of characters to the stream.
        /// </summary>
        /// <param name="buffer">A character array containing the data to write.</param>
        /// <param name="index">The index into buffer at which to begin writing.</param>
        /// <param name="count">The number of characters to read from buffer.</param>
        /// <exception cref="ArgumentException">
        /// The buffer length minus index is less than count.
        /// </exception>
        /// <exception cref="ArgumentNullException">
        /// buffer is a null reference (Nothing in Visual Basic). 
        /// </exception>
        /// <exception cref="ArgumentOutOfRangeException">
        /// index or count is negative.
        /// </exception>
        /// <exception cref="ObjectDisposedException">
        /// AutoFlush is true or the StreamWriter buffer is full, and current writer is closed.
        /// </exception>
        /// <exception cref="IIOException">
        /// An I/O error has occurred.
        /// </exception>
        /// <exception cref="NotSupportedException">
        /// AutoFlush is true or the StreamWriter buffer is full, 
        /// and the contents of the buffer cannot be written to the 
        /// underlying fixed size stream because the StreamWriter is at the end the stream.
        /// </exception>
        [SecuritySafeCritical]
        void Write(char[] buffer, int index, int count);

        /// <summary>
        /// Writes a string to the stream.
        /// </summary>
        /// <param name="value">The string to write to the stream. If value is null, nothing is written.</param>
        /// <exception cref="ObjectDisposedException">
        /// AutoFlush is true or the StreamWriter buffer is full, and current writer is closed.
        /// </exception>
        /// <exception cref="IIOException">
        /// An I/O error has occurred.
        /// </exception>
        /// <exception cref="NotSupportedException">
        /// AutoFlush is true or the StreamWriter buffer is full, 
        /// and the contents of the buffer cannot be written to the 
        /// underlying fixed size stream because the StreamWriter is at the end the stream.
        /// </exception>
        [SecuritySafeCritical]
        void Write(string value);
    }
}